Comprehensive per-topic brownfield documentation for future
developers and AI coding agents picking the project up cold.
Twelve numbered files under docs/ + an ADR + CLAUDE.md +
for-the-badge styled README badges. No source changes.

What landed:

* docs/00-project-overview.md  — what / who / target users / status
                                  / production-ready vs experimental
* docs/01-local-setup.md       — prerequisites, install, run, test,
                                  required services, common issues, env vars
* docs/02-architecture.md      — quick-scan layers, data flow, storage,
                                  external systems, tradeoffs, what
                                  this architecture is NOT
* docs/03-code-map.md          — per-folder + per-file purpose with
                                  approximate LOC and related files
* docs/04-main-flows.md        — entry points + key files + failure
                                  modes for: auth, session lifecycle,
                                  HITL, background jobs, ingestion,
                                  deployment, error handling
* docs/05-configuration.md     — env vars, config layers, per-skill
                                  config, feature toggles, secrets,
                                  safe defaults, validators
* docs/06-data-model.md        — backends, entities, relationships,
                                  migrations, persistence assumptions,
                                  vector index, backup notes
* docs/07-integrations.md      — LLM providers, MCP servers, auth,
                                  queues, observability mocks (incident
                                  example), code-review mocks, memory
                                  layers, CI services, local overrides
* docs/08-testing.md           — pytest config, run commands, suite
                                  structure (149 files, 1265 tests),
                                  what's covered well vs weakly,
                                  CI gates, how to add a test
* docs/09-build-deploy-release — bundler pipeline, CI workflow,
                                  containerisation status (none),
                                  air-gap deploy procedure, release
                                  flow, rollback, versioning
* docs/10-known-risks-and-todos — TODO/FIXME inventory, hardcoded
                                  values, weak features, security
                                  surfaces, migration risks,
                                  concurrency risks, ops risks
* docs/11-agent-handoff.md     — 20-line summary, top 20 files to
                                  read, command allow/deny lists,
                                  8 architectural rules, coding
                                  conventions, common traps,
                                  unfinished work, recommended next
                                  tasks
* docs/adr/0001-current-architecture.md
                                — decision baseline as of v1.5,
                                  consequences (positive / negative /
                                  neutral), alternatives considered,
                                  open questions for future ADRs

* CLAUDE.md                    — project context loaded by Claude
                                  Code (and equivalent agents) every
                                  session. DO / DO NOT lists,
                                  architectural rules recap, common
                                  traps, where-to-find-what map.

* README.md                    — added for-the-badge styled badges
                                  (Python, LangGraph, FastMCP, CI,
                                  SonarCloud quality gate + coverage,
                                  test count, ruff, pyright). Body
                                  unchanged from the v1.5 doc-
                                  consolidation PR.

* .gitignore                   — explicit allowlist for the new
                                  docs/* files + docs/adr/ next to
                                  the existing DESIGN/AIRGAP/DEVELOPMENT
                                  entries. The ``docs/*`` blanket
                                  ignore stays so accidentally-
                                  generated scratch doesn't leak in.

Documentation conventions used throughout:
- Inline source references (file:line where useful) for every
  non-obvious claim.
- Inferences explicitly tagged "Inference:" so future readers can
  re-verify.
- Unknowns explicitly tagged "Unknown" rather than guessed.
- No real secrets — only env-var names and CI dummy patterns.

Suite: 1265 passed (unchanged — docs-only). Ruff clean.